Update usage types in the docs by sureshanaparti · Pull Request #504 · apache/cloudstack-documentation

sureshanaparti · 2025-05-13T08:52:19Z

This PR updates/sync the usage types in docs with the API response and code.

Current doc: https://docs.cloudstack.apache.org/en/latest/adminguide/usage.html#usage-types.

list usagetypes API response =>

(usageenv) 🐱 > list usagetypes 
{
  "count": 25,
  "usagetype": [
    {
      "description": "Running Vm Usage",
      "usagetypeid": 1
    },
    {
      "description": "Allocated Vm Usage",
      "usagetypeid": 2
    },
    {
      "description": "IP Address Usage",
      "usagetypeid": 3
    },
    {
      "description": "Network Usage (Bytes Sent)",
      "usagetypeid": 4
    },
    {
      "description": "Network Usage (Bytes Received)",
      "usagetypeid": 5
    },
    {
      "description": "Volume Usage",
      "usagetypeid": 6
    },
    {
      "description": "Template Usage",
      "usagetypeid": 7
    },
    {
      "description": "ISO Usage",
      "usagetypeid": 8
    },
    {
      "description": "Snapshot Usage",
      "usagetypeid": 9
    },
    {
      "description": "Security Group Usage",
      "usagetypeid": 10
    },
    {
      "description": "Load Balancer Usage",
      "usagetypeid": 11
    },
    {
      "description": "Port Forwarding Usage",
      "usagetypeid": 12
    },
    {
      "description": "Network Offering Usage",
      "usagetypeid": 13
    },
    {
      "description": "VPN users usage",
      "usagetypeid": 14
    },
    {
      "description": "VM Disk usage(I/O Read)",
      "usagetypeid": 21
    },
    {
      "description": "VM Disk usage(I/O Write)",
      "usagetypeid": 22
    },
    {
      "description": "VM Disk usage(Bytes Read)",
      "usagetypeid": 23
    },
    {
      "description": "VM Disk usage(Bytes Write)",
      "usagetypeid": 24
    },
    {
      "description": "VM Snapshot storage usage",
      "usagetypeid": 25
    },
    {
      "description": "Volume on secondary storage usage",
      "usagetypeid": 26
    },
    {
      "description": "VM Snapshot on primary storage usage",
      "usagetypeid": 27
    },
    {
      "description": "Backup storage usage",
      "usagetypeid": 28
    },
    {
      "description": "Bucket storage usage",
      "usagetypeid": 29
    },
    {
      "description": "Network usage",
      "usagetypeid": 30
    },
    {
      "description": "VPC usage",
      "usagetypeid": 31
    }
  ]
}
(usageenv) 🐱 >

code =>

https://github.com/apache/cloudstack/blob/39c5641cbe674b19bc77082b850565f634a7cb84/api/src/main/java/org/apache/cloudstack/usage/UsageTypes.java#L24-L50

📚 Documentation preview 📚: https://cloudstack-documentation--504.org.readthedocs.build/en/504/

sureshanaparti · 2025-05-13T08:52:44Z

@blueorangutan docbuild

blueorangutan · 2025-05-13T08:54:05Z

@sureshanaparti a Jenkins job has been kicked to build the document. I'll keep you posted as I make progress.

blueorangutan · 2025-05-13T08:55:07Z

QA-Doc build preview: https://qa.cloudstack.cloud/builds/docs-build/pr/504. (QA-JID 339)

sureshanaparti · 2025-05-13T09:11:38Z

@rajujith Update the usage types (still the record formats for these to be updated)

sureshanaparti · 2025-05-14T08:30:52Z

@blueorangutan docbuild

blueorangutan · 2025-05-14T08:32:05Z

@sureshanaparti a Jenkins job has been kicked to build the document. I'll keep you posted as I make progress.

blueorangutan · 2025-05-14T08:33:08Z

QA-Doc build preview: https://qa.cloudstack.cloud/builds/docs-build/pr/504. (QA-JID 342)

rajujith

LGTM.

DaanHoogland · 2025-05-26T13:33:29Z

quite frankly I am against this change. there is a list usage types API and it should document the usage types. adding/updating the docs on this in creating a split source of truth.

abh1sar · 2025-07-18T09:26:20Z

quite frankly I am against this change. there is a list usage types API and it should document the usage types. adding/updating the docs on this in creating a split source of truth.

@DaanHoogland, The doc in its current form has already diverged from the source of truth, so adding the missing usage types wouldn’t introduce any additional inconsistency.

As a potential improvement, perhaps we could sync the doc with the missing Usage Types and clearly mention that users should refer to the list Usage Types API for the most up-to-date information?

I was hoping to add some details related to Backup usage to the doc, but currently, Backup isn’t even mentioned as a usage type.

DaanHoogland · 2025-08-06T08:41:29Z

@abh1sar ,

quite frankly I am against this change. there is a list usage types API and it should document the usage types. adding/updating the docs on this in creating a split source of truth.

@DaanHoogland, The doc in its current form has already diverged from the source of truth, so adding the missing usage types wouldn’t introduce any additional inconsistency.

I do not believe that is a reason to let it like this. I think the paragraph should be removed and replaced with a link/command to retrieve the data from the API. We are creating a path to continuous maintenance and probably technical debt if we allow for documentation of things which are also documented in code.

As a potential improvement, perhaps we could sync the doc with the missing Usage Types and clearly mention that users should refer to the list Usage Types API for the most up-to-date information?

If this is implemented in an update script we still need to have it run and humans will forget.

I was hoping to add some details related to Backup usage to the doc, but currently, Backup isn’t even mentioned as a usage type.

That should be solved in the source (i.e. the API doc, not in this file)

cc @Pearl1594 @sureshanaparti @rajujith

weizhouapache

code lgtm

DaanHoogland · 2025-10-22T14:16:34Z

@sureshanaparti @rajujith @weizhouapache , I do not like this way maintaining this information but am not going to reject it. Should we merge this?

weizhouapache · 2025-10-22T18:34:44Z

@sureshanaparti @rajujith @weizhouapache , I do not like this way maintaining this information but am not going to reject it. Should we merge this?

@DaanHoogland
do you have a way to maintain the information ?

DaanHoogland · 2025-10-23T07:01:23Z

@sureshanaparti @rajujith @weizhouapache , I do not like this way maintaining this information but am not going to reject it. Should we merge this?

@DaanHoogland do you have a way to maintain the information ?

In my opinion we should return the description in the table with the list usagetypes ouput, and only describe examples and use cases here. (#504 (comment))

Copilot

Pull request overview

This PR updates the usage types documentation to sync it with the current CloudStack API response and codebase. The documentation was outdated, referencing "Cloud.com" instead of "CloudStack" and missing several usage types (IDs 21-31).

Changes:

Updated "Cloud.com" references to "CloudStack" in usage type descriptions
Corrected type 9 description from "Template" to "Snapshot"
Added missing usage types 21-31 including VM disk I/O metrics, snapshots, backup, bucket, network, and VPC usage types

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-15T06:18:13Z

source/adminguide/usage.rst

-|                  |                                   | from when a Template        |
+|                  |                                   | from when a Snapshot        |
 |                  |                                   | has been created to         |
 |                  |                                   | the time it have been       |


Grammar error: 'it have been' should be 'it has been' to maintain subject-verb agreement.

Suggested change

| | | the time it have been |

| | | the time it has been |

Copilot · 2026-01-15T06:18:13Z

source/adminguide/usage.rst

+| 25               | VM\_SNAPSHOT                      | Tracks the total time a     |
+|                  |                                   | VM Snapshot has been        |
+|                  |                                   | created to the time when    |
+|                  |                                   | it has been destroyed.      |


Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Update usage types in the docs

d7adfb8

sureshanaparti requested review from DaanHoogland and rajujith May 13, 2025 09:10

Update Cloud.com

ac91a56

rajujith approved these changes May 20, 2025

View reviewed changes

yadvr added this to the 4.20.1 milestone Jun 3, 2025

yadvr changed the base branch from 4.19 to 4.20 June 3, 2025 08:17

yadvr requested a review from Pearl1594 June 3, 2025 08:17

yadvr changed the base branch from 4.20 to 4.19 June 3, 2025 08:18

yadvr assigned DaanHoogland Jun 3, 2025

yadvr modified the milestones: 4.20.1, 4.19.3 Jun 3, 2025

sureshanaparti modified the milestones: 4.19.3, 4.19.4 Jul 21, 2025

yadvr modified the milestones: 4.19.4, 4.20.2 Aug 28, 2025

weizhouapache approved these changes Oct 17, 2025

View reviewed changes

weizhouapache changed the base branch from 4.19 to 4.20 October 17, 2025 09:25

weizhouapache modified the milestones: 4.20.2, 4.20.3 Nov 11, 2025

sureshanaparti linked an issue Jan 7, 2026 that may be closed by this pull request

[Doc] Usage Types update apache/cloudstack#10813

Open

vishesh92 requested a review from Copilot January 15, 2026 06:16

Copilot started reviewing on behalf of vishesh92 January 15, 2026 06:16 View session

Copilot AI reviewed Jan 15, 2026

View reviewed changes

Conversation

sureshanaparti commented May 13, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sureshanaparti commented May 13, 2025

Uh oh!

blueorangutan commented May 13, 2025

Uh oh!

blueorangutan commented May 13, 2025

Uh oh!

sureshanaparti commented May 13, 2025

Uh oh!

sureshanaparti commented May 14, 2025

Uh oh!

blueorangutan commented May 14, 2025

Uh oh!

blueorangutan commented May 14, 2025

Uh oh!

rajujith left a comment

Choose a reason for hiding this comment

Uh oh!

DaanHoogland commented May 26, 2025

Uh oh!

abh1sar commented Jul 18, 2025

Uh oh!

DaanHoogland commented Aug 6, 2025

Uh oh!

weizhouapache left a comment

Choose a reason for hiding this comment

Uh oh!

DaanHoogland commented Oct 22, 2025

Uh oh!

weizhouapache commented Oct 22, 2025

Uh oh!

DaanHoogland commented Oct 23, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

sureshanaparti commented May 13, 2025 •

edited by github-actions bot

Loading